Skip to content

feat(types, pass1, stage2, stage3, planner, viewer): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions - #1374

Merged
zzylol merged 6 commits into
mainfrom
test/deployment-exclusions
Nov 17, 2026
Merged

zzylol merged 6 commits into
mainfrom
test/deployment-exclusions

Conversation

@zzylol

@zzylol zzylol commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Problem: a deployment could only say which sketches it builds and whether it keeps raw data or query-time results, and those were applied in two places (Pass 1, and two Stage 2 rules). It could not say "no rate state merged across windows", "no counter extrapolation", or "never select a query-time scan". So rate(c[5m]) was planned as stored Rate windows on a target that cannot merge them, and the benchmark harness patched an environment-variable hook into Stage 3.
  • Change: DeploymentCapabilities is the one place a target's restrictions live. DeploymentCapabilities::exclusions() expands every capability a target lacks, and each candidate the caller excludes, into CandidateExclusions. Stage 2 applies them as one filter (PruneReason::ExcludedByDeployment(source)). Stage 3 reports no plan left as RejectionCause::ExcludedByDeployment.
  • Effect: for rate(c[5m]) every 60 s over 1,000 counter series, a target without mergeable rate state gets query-time SummaryAgg(Rate) → FinalizeExactAccumulator at 0.367671 per second, instead of stored windows at 0.279284. A target without counter extrapolation gets no plan, and the rejection names counter_not_extrapolated (7 candidates). The default capabilities select the same plans as before.

Part of #1370. This is harness PR P1 of #1317's design, with CandidateExclusion unified with the deployment capability table as #1370 asks. The Stage 2 placement and the tests were approved before implementation.

Review guide

  • Base: main at 1760a69f5; head ceb78acf4. Not stacked. Five commits:
    1. the approved tests, rebased (one conflict, resolved as described below);
    2. the implementation;
    3. the viewer and its fixture;
    4. a Stage 3 fix: the default deployment's own exclusion does not turn Infeasible into ExcludedByDeployment;
    5. review fixes: Pass 1 skips summaries excluded outright, the rejection keeps the costing failures, validate refuses self-contradicting exclusions, and smaller cleanups (see "Review fixes" below).
  • Read first (needs careful review):
    • crates/types/src/deployment_capabilities/mod.rs: exclusions() and validate.
    • crates/types/src/deployment_capabilities/exclusion.rs: CandidateExclusion::matches, invalid_reason, family_excluded_outright.
    • crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs: without_excluded_families.
    • crates/stage2-physical-optimization/src/candidate.rs: the one filter in offered_physical_properties.
    • crates/stage3-plan-selection/src/report.rs: excluded_by_deployment, and its two call sites in lib.rs.
  • Mechanical:
    • pass1_memo(memo, None) → pass1_memo(memo, &[]) in tests; the facade and the devtools stage runner pass &capabilities.exclusions().
    • asap-cost's private measure_name became AggIntent::kind_name in asap-types.
    • tools/dag-viewer/test-fixtures/p90-kll.json was regenerated with the README command (see Verification).
  • Rebase conflict: main (refactor: tools and snapshots over the #1207 memo, edges and contexts (#1207 PR 9) #1239) removed the viewer's REJECTION_CAUSES list, and with it the rejection-cause half of viewer_contract.rs (the test is now viewer_knows_every_view_refresh). The tests commit's addition to that half is dropped, since no viewer list is left to check. assert_excluded_by_deployment in deployment_exclusions.rs still asserts that the cause is not a failed check.

Behavior: before → after

The user's input: a workload with one counter query, planned for a target that cannot keep rate state across windows.

// workload.json
{"query_workload": {"language": "promql", "repeating_queries": [
   {"query": "rate(c[5m])", "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}},
    "requirements": {}, "predictability": {"predictable": {"known_at": null}}}]},
 "data_workload": {"arrival": {"ingesting": {"rows_per_second": 1000.0}},
   "sources": {"c": {"series_count": 1000, "metric_type": "counter", "sample_interval": 1000}}}}
// capabilities.json (asap_planner --deployment-capabilities)
{"state_not_mergeable_across_windows": [{"exact": "Rate"}, {"exact": "Increase"}]}
Before (main) After (this PR)
capabilities state_not_mergeable_across_windows is an unknown field, so the file is refused accepted
plan ingestion Scan → ingestion SummaryTumblingWindowChain(Rate) → TimeRange → SummaryMerge → FinalizeExactAccumulator, 0.279284 per second query-time Scan → TimeRange → SummaryAgg(Rate) → FinalizeExactAccumulator, 0.367671 per second
Stage 2 report — 3 alternatives pruned; the text count line reads ExcludedByDeployment(state_not_mergeable_across_windows) 3
{"counter_semantics": {"extrapolation": false}} unknown field no plan: NoValidCandidate([Rejection { cause: ExcludedByDeployment, reason: "… counter_not_extrapolated (7 candidates) … may be infeasible without …" }])
{"excluded_candidates": [{"timing": "query_time", "operator": "Scan"}, …]} (the sweep's "stored" arm) needs ASAP_SB_FORBID patched into Stage 3 sum_over_time(m[5m]) reads an ingestion-time chain of exact sums, at 0.113237 instead of 0.060534 per second

Rejection cause under MVP capabilities ({"raw_data_retained": false, "query_time_results_retained": false}, which plan_installable defaults to): 5 of the 77 sketch-heavy workloads have no plan. main reports them as Infeasible; this PR reports them as ExcludedByDeployment with the reason query 0 has no candidate left to answer it; excluded by the deployment: raw_data_not_retained (4 candidates); the workload may be infeasible without these exclusions too (for repeat-rate-and-l2…, the MILP form: no plan is left (the selection MILP is infeasible); …). The 5 are promql-entropy__r4-10hz-24h…, sql-entropy-client-ip…, sql-l2-client-ip…, control-l2-16-resolvers… and repeat-rate-and-l2…. When some execution could not be costed, the reason ends with the same ; executions left out because they could not be costed: … that Infeasible gives (none of these 5 has one).

Stage 2 count line (text output): a pruned alternative a deployment exclusion matched is counted per source, e.g. ExcludedByDeployment(query_time_results_not_retained) 502 where main printed QueryTimeResultsNotRetained 502. Across the 47 viewer workloads under the default deployment, this is the only difference from main besides MILP solve times.

This serves the measurement harness, whose sweep arms and target profiles need typed restrictions. It also serves #1370's capability-limited targets.

Interfaces

Every declaration below is in this PR, bodies elided.

crates/types/src/deployment_capabilities/mod.rs (was deployment_capabilities.rs)

 /// What the deployment's executor can run and keep. Planning reads it in
-/// Stage 1 (`supported_summaries`), Stage 2 (`query_time_results_retained`)
-/// and Stage 3 (`raw_data_retained`).
+/// Pass 1 and Stage 2, as the exclusions it expands into (the facade
+/// expands them once).
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(default, deny_unknown_fields)]
 pub struct DeploymentCapabilities {
     pub supported_summaries: Option<Vec<SupportedSummary>>,
     pub raw_data_retained: bool,
     pub query_time_results_retained: bool,
+    /// What the executor's counter functions do; default: they handle
+    /// resets and extrapolate, as PromQL's do.
+    pub counter_semantics: CounterSemanticsSupport,
+    /// State families the executor builds and finalizes within one
+    /// evaluation only, e.g. `[{"exact": "Rate"}]`; default none.
+    pub state_not_mergeable_across_windows: Vec<SummaryFamily>,
+    /// Candidates the caller rules out directly, e.g. a benchmark arm with
+    /// no query-time scan; default none.
+    pub excluded_candidates: Vec<CandidateExclusion>,
 }
+/// What a deployment's counter functions do. JSON: an object; an omitted field is `true`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct CounterSemanticsSupport {
+    /// A drop in a counter is a reset and is added back (rate, increase, irate, resets).
+    pub reset_handling: bool,
+    /// The increase is extrapolated to the range's ends (rate, increase, delta).
+    pub extrapolation: bool,
+}
+/// Which capability an exclusion comes from; Stage 2's prune reason names it.
+/// JSON: snake_case, e.g. `"raw_data_not_retained"`. `Display`: the same name,
+/// or `excluded_candidates[0]`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExclusionSource {
+    SummaryNotSupported,
+    ReadoutNotSupported,
+    RawDataNotRetained,
+    QueryTimeResultsNotRetained,
+    CounterResetsNotHandled,
+    CounterNotExtrapolated,
+    StateNotMergeableAcrossWindows,
+    /// The caller's `excluded_candidates[index]`.
+    ExcludedCandidate { index: usize },
+}
+impl ExclusionSource {
+    /// Whether the default deployment has this source too (only
+    /// `QueryTimeResultsNotRetained`); Stage 3 blames the deployment for the others.
+    pub fn in_default_deployment(self) -> bool;
+}
+impl fmt::Display for ExclusionSource;
+/// One exclusion a deployment's capabilities expand into, with its source.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DeploymentExclusion {
+    pub source: ExclusionSource,
+    pub exclusion: CandidateExclusion,
+}
 impl DeploymentCapabilities {
+    /// The exclusions these capabilities expand into, in the order: supported
+    /// summaries, raw data, query-time results, counter resets, counter
+    /// extrapolation, unmergeable state, then `excluded_candidates`. The default's
+    /// only one is `{timing: query_time, kept_across_evaluations: true}`.
+    /// A counter semantics left out expands into one `aggregate_measure`
+    /// exclusion per counter function and one `summary_family` exclusion per
+    /// counter state that needs it: without extrapolation `rate`, `increase`,
+    /// `delta`, `Exact(Rate)`, `Exact(Increase)`; without reset handling
+    /// `rate`, `increase`, `i_rate`, `resets`, `Exact(Rate|Increase|IRate)`.
+    /// A family not mergeable across windows expands into `{family, operator:
+    /// SummaryTumblingWindowChain}` and `{family, kept_across_evaluations: true}`.
+    pub fn exclusions(&self) -> Vec<DeploymentExclusion>;
-    pub fn supports(&self, summary_type: &SketchAlgorithm, readout: StatisticKind) -> bool;
     /// … also refuses an exclusion of `excluded_candidates` that cannot be applied.
     pub fn validate(&self, data: &DataWorkload) -> Result<(), DeploymentCapabilitiesError>;
 }
 }
-pub fn summary_supported(
-    supported_summaries: Option<&[SupportedSummary]>,
-    summary_type: &SketchAlgorithm,
-    readout: StatisticKind,
-) -> bool;
 pub enum DeploymentCapabilitiesError {
     StoredDataNotRetained { arrival: DataArrival },
+    /// Bad input: `excluded_candidates[index]` sets no field, has an empty
+    /// range or an α outside (0, 1), contradicts itself, or names no measure.
+    #[error("excluded candidate {index}: {reason}")]
+    InvalidExclusion { index: usize, reason: String },
 }

crates/types/src/deployment_capabilities/exclusion.rs (new)

+/// Physical candidates whose description matches every field that is set
+/// (AND; an unset field matches anything). JSON: an object; an unknown field is refused.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct CandidateExclusion {
+    pub timing: Option<ExecutionTiming>,
+    /// Lifetime `AcrossEvaluations` (`Some(true)`) or not.
+    pub kept_across_evaluations: Option<bool>,
+    pub operator: Option<OperatorKind>,
+    /// An operator with a `Reduction`: per entity (`Some(true)`) or grouped.
+    pub per_entity_reduction: Option<bool>,
+    /// An `Aggregate` (only; never a state build) one of whose measures has
+    /// this `AggIntent` kind, e.g. `"rate"`. To rule out a query-time `Rate`
+    /// state too, add `{"summary_family": {"exact": "Rate"}}`.
+    pub aggregate_measure: Option<String>,
+    /// A state build (`SummaryAgg`, chain) of this family.
+    pub summary_family: Option<SummaryFamily>,
+    /// A state build whose θ is in this range.
+    pub sketch_parameter_range: Option<SketchParameterRange>,
+    /// A `SummaryEstimate` of this statistic from this sketch's state.
+    pub readout: Option<SketchReadout>,
+}
+/// A statistic read from a sketch's state, e.g. `{"summary_type": "Kll", "statistic": "Total"}`.
+pub struct SketchReadout { pub summary_type: SketchAlgorithm, pub statistic: StatisticKind }
+/// One physical candidate as an exclusion matches it. `C` is how the
+/// operator names its inputs: memo groups in Stage 2, plan node ids when a
+/// test checks a selected plan.
+pub struct CandidateDescription<'a, C> {
+    pub operator: &'a Operator<C>,
+    pub parameters: Option<&'a SketchParams>,
+    pub physical_properties: PhysicalProperties,
+    /// For a `SummaryEstimate`: the summary type of the state it reads.
+    pub read_summary_type: Option<&'a FieldDataType>,
+}
+impl CandidateExclusion {
+    pub fn matches<C>(&self, candidate: &CandidateDescription<'_, C>) -> bool;
+    /// The family this exclusion rules out outright: it sets `summary_family`
+    /// and no other field (as `supported_summaries` does for an algorithm it
+    /// does not list). Pass 1 skips such a sketch algorithm.
+    pub fn family_excluded_outright(&self) -> Option<SummaryFamily>;
+    /// The readout this exclusion rules out outright: it sets `readout` and no
+    /// other field. Pass 1 skips that algorithm for a measure reading that statistic.
+    pub fn readout_excluded_outright(&self) -> Option<SketchReadout>;
+    /// Why `validate` refuses it (sets no field, two fields that match no
+    /// operator in common, invalid range, range of another algorithm than its
+    /// family, unknown measure), or `None`.
+    pub fn invalid_reason(&self) -> Option<String>;
+}

crates/types/src/summary_type/family.rs (new) and parameters.rs

+/// A summary state's family without θ. JSON: `{"sketch": "Kll"}`, `{"exact": "Sum"}`.
+#[serde(rename_all = "snake_case")]
+pub enum SummaryFamily { Sketch(SketchAlgorithm), Exact(ExactKind) }
+impl SummaryFamily { pub fn of(summary_type: &FieldDataType) -> Option<Self>; }
+/// An inclusive range of one sketch parameter. JSON: `{"kll_k": {"at_most": 1403}}`.
+#[serde(rename_all = "snake_case", deny_unknown_fields)]
+pub enum SketchParameterRange {
+    KllK { at_least: Option<u32>, at_most: Option<u32> },
+    KmvK { at_least: Option<u32>, at_most: Option<u32> },
+    #[serde(rename = "ddsketch_alpha")]
+    DDSketchAlpha { at_least: Option<f64>, at_most: Option<f64> },
+}
+impl SketchParameterRange {
+    pub fn algorithm(&self) -> SketchAlgorithm;
+    pub fn contains(&self, parameters: &SketchParams) -> bool;
+    /// Why the range is bad input: `at_least` above `at_most`, or an α
+    /// outside (0, 1); `None` when valid.
+    pub fn invalid_reason(&self) -> Option<String>;
+}

crates/types/src/ir/operator/kind.rs (moved from crates/cost/src/measured.rs, which re-exports it)

-pub fn of(payload: &Payload) -> Self;
+pub fn of<C>(operator: &Operator<C>) -> Self;

crates/stage2-physical-optimization/src/lib.rs

 pub fn generate_physical_asap_memo_candidates(
     logical: &LogicalASAPMemoCandidates,
     data: &DataWorkload,
-    capabilities: &DeploymentCapabilities,
+    exclusions: &[DeploymentExclusion],
 ) -> PhysicalASAPMemoCandidates;

crates/types/src/stages/pruning.rs and crates/stage3-plan-selection/src/report.rs

 pub enum PruneReason {
     NoIngestionPipeline,
-    RawDataNotRetained,
-    QueryTimeResultsNotRetained,
     InputHasNoBuildableProducer,
     ReachesNoQueryOutput,
     CountMinWeightsNotProvenNonNegative,
+    /// Stage 2: the deployment's exclusions match it; names their source.
+    ExcludedByDeployment(ExclusionSource),
     DominatedBy(PhysicalCandidateId),
     UsageNotCostable,
 }
 pub enum RejectionCause {
     AccuracyTargetMissed,
     NoAccuracyGuarantee,
     LatencyBoundExceeded,
     LatencyOverRepeatInterval,
     OverClusterCapacity,
     CostNotRepresentable,
     Costlier,
     Slower,
     MoreMemory,
     TiedLostOnEnumerationOrder,
     Infeasible,
+    /// No plan is left without the deployment's exclusions. The reason names the
+    /// query or the infeasible MILP, then each source with its pruned count, e.g.
+    /// `counter_not_extrapolated (7 candidates)`, and says the workload may be
+    /// infeasible without them too. Not a failed check.
+    ExcludedByDeployment,
 }

crates/planner/src/lib.rs: re-exports CandidateExclusion, CounterSemanticsSupport, ExclusionSource, SketchReadout, SketchParameterRange, SummaryFamily.

crates/types/src/ir/operator/agg_intent.rs, crates/types/src/ir/schema/mod.rs and crates/stage1-pass1-per-computation-candidates/src/lib.rs

 impl AggIntent<ColumnId> {
+    /// The measure's JSON `kind`, e.g. `"rate"`; moved from `asap-cost`'s
+    /// private `measure_name`, which keys measured operation costs by it.
+    pub fn kind_name(&self) -> String;
+    /// Whether `name` is some measure's kind (`"rate"` yes, `"rte"` no).
+    pub fn is_kind_name(name: &str) -> bool;
 }
 impl Schema {
+    /// The summary state type this schema carries (its first non-plain
+    /// field), e.g. `Sketch(Kll)`; Stage 2 reads it for a readout's state.
+    pub fn summary_state_type(&self) -> Option<&FieldDataType>;
 }
-pub fn pass1_memo(
-    memo: Memo,
-    supported_summaries: Option<&[SupportedSummary]>,
-) -> Result<Memo, PerComputationCandidateError>;
+/// Pass 1 skips a summary whose sketch algorithm, or the readout the measure
+/// reads from it, one of `exclusions` rules out outright
+/// (`family_excluded_outright`, `readout_excluded_outright`); Stage 2 prunes
+/// everything else the deployment cannot run.
+pub fn pass1_memo(
+    mut memo: Memo,
+    exclusions: &[DeploymentExclusion],
+) -> Result<Memo, PerComputationCandidateError>;

Removed by this PR (the - lines above):

  • PruneReason::RawDataNotRetained and PruneReason::QueryTimeResultsNotRetained. They are now ExcludedByDeployment(ExclusionSource::RawDataNotRetained) and ExcludedByDeployment(ExclusionSource::QueryTimeResultsNotRetained).
  • The Pass 1 summary filter without_unsupported_summaries and the supported_summaries parameter of pass1_memo and computation_targets. Pass 1 now reads the same exclusions() list (without_excluded_summaries), only to skip a sketch algorithm excluded outright or whose readout of the measure's statistic is excluded outright; Stage 2 prunes everything narrower.
  • DeploymentCapabilities::supports and the free function summary_supported. Their only callers were the Pass 1 filter and one installable test, which now reads supported_summaries directly.
  • asap-cost's private measure_name, moved to AggIntent::kind_name.
  • The Pass 1 test tests::targets::unsupported_summaries_are_not_offered, which tested the deleted filter. exact_only_capabilities_offer_no_summary replaces it for the new Pass 1 skip; Stage 2's unsupported_summaries_and_readouts_are_pruned covers the Stage 2 side.

Wire change: a Stage 2 pruned candidate's reason for these capabilities is now {"excluded_by_deployment": "raw_data_not_retained"} (or {"excluded_by_deployment": {"excluded_candidate": {"index": 0}}}) instead of "raw_data_not_retained". The viewer shows it as "excluded by the deployment: raw data not retained".

Usage (what the integration tests run):

// The deployment: no rate or increase state kept across windows.
let capabilities = DeploymentCapabilities {
    state_not_mergeable_across_windows: vec![
        SummaryFamily::Exact(ExactKind::Rate),
        SummaryFamily::Exact(ExactKind::Increase),
    ],
    ..Default::default()
};
// The facade expands `capabilities.exclusions()` once and passes the list to
// Pass 1 and Stage 2, which prunes every alternative one of them matches.
let models = PlanningModels::builtin().with_deployment_capabilities(&capabilities);
// `rate(c[5m])` every 60 s over 1,000 counter series, lowered and planned.
let run = run_planning_stages_over(roots, &entries, &data, models)?.run;
// The plan: query-time Scan → TimeRange → SummaryAgg(Rate) → Finalize, 0.367671 per second.
let (plan, selection) = run.selection.as_ref().unwrap();

Design scope

New item Scope Why it is general
deployment_capabilities/exclusion.rs: CandidateExclusion, SketchReadout, CandidateDescription deployment input (asap-types), read by Pass 1 and Stage 2 It describes physical candidates by operator, timing, lifetime, θ, measure and readout, which is the physical vocabulary every stage already has. It is not tied to one engine or one sweep arm.
DeploymentCapabilities::{counter_semantics, state_not_mergeable_across_windows, excluded_candidates}, CounterSemanticsSupport, ExclusionSource, DeploymentExclusion, exclusions() deployment input They hold a target's capabilities and how they expand. The sweep's exclusions and an engine's profile are both lists of the same type, as #1370 asks.
summary_type/family.rs: SummaryFamily; SketchParameterRange summary types (θ vocabulary) They are a family without θ and a range of θ, next to SketchParams. A calibration filter can reuse them.
ir/operator/kind.rs: OperatorKind (moved) IR It names an operator without its arguments. It is not cost-specific, and asap-types needs it.
PruneReason::ExcludedByDeployment, RejectionCause::ExcludedByDeployment stage reports They use the existing report shapes, with one reason per filter.
AggIntent::{kind_name, is_kind_name} (moved from asap-cost's private measure_name) IR The measure's JSON kind, shared by measured operation costs and exclusions.
CandidateExclusion::{family_excluded_outright, readout_excluded_outright} deployment input Say when an exclusion rules out a whole family or readout, which is what lets Pass 1 skip it without a second filter.
ExclusionSource::in_default_deployment, Display for ExclusionSource deployment input The source's own facts: whether the default deployment has it, and its JSON name. Stage 3 and the stage text read them instead of rebuilding the default capabilities.
Schema::summary_state_type IR schema The state type a schema carries; Stage 2 reads it for the state a readout reads, and plan-node matching does too.

Why the names changed from the approved plan:

  • SelectionOptions and select_plan_with are gone. The exclusions are a deployment input, and PlanningModels::deployment_capabilities already reaches Stage 2.
  • PlanningModels::selection_options is not needed.
  • The causes are ExcludedByDeployment, not ExcludedBySelectionOptions, because one cause now covers both capabilities and caller exclusions.

Algorithm changes

Problem: the restrictions were applied in three places with three mechanisms: Pass 1 for summaries, and two separate Stage 2 rules for retention. Nothing could express counter semantics, state mergeability, measures or θ ranges.

Before:

  1. Pass 1 dropped unsupported summaries (without_unsupported_summaries).
  2. Stage 2 pruned raw-data and query-time-result alternatives, each with its own reason.
  3. Stage 3 reported an empty plan space as Infeasible.

After:

  1. DeploymentCapabilities::exclusions() expands everything into one list, in this order:
    • supported summaries: a family exclusion for each sketch algorithm not listed, and a readout exclusion for each statistic a listed algorithm answers but the deployment does not;
    • raw data: {query_time, Scan} and {Scan, kept_across_evaluations};
    • query-time results: {query_time, kept_across_evaluations};
    • counter reset handling, then counter extrapolation: one aggregate_measure exclusion per counter function and one summary_family exclusion per counter state that needs it (irate and IRate need reset handling only);
    • unmergeable state families: {family, operator: SummaryTumblingWindowChain} and {family, kept_across_evaluations: true};
    • excluded_candidates[i].
  2. Pass 1 (without_excluded_summaries, run last in computation_targets) drops each Summary(algorithm) way, a fused computation's included, whose Sketch(algorithm) family one exclusion of the same list rules out outright (summary_family set and nothing else), or whose readout of the measure's statistic one rules out outright (readout set and nothing else; the outer measure's statistic for a fused computation), as main did for supported_summaries. Stage 2 would prune every build or readout of it, so this only saves work. Exact accumulators and every narrower exclusion (mergeability, θ ranges) are left to Stage 2.
  3. Stage 2 (offered_physical_properties) describes each offered (τ, ℓ) as a CandidateDescription: its operator, θ and physical properties, and for a SummaryEstimate the state type of the group it reads. After the Count-Min and no-ingestion rules, it records the first matching exclusion as ExcludedByDeployment(source). The existing propagation (InputHasNoBuildableProducer, ReachesNoQueryOutput) removes whatever depended on it.
  4. Stage 3 handles two cases: a query with no answering execution, and an infeasible MILP. In both, it returns one ExcludedByDeployment rejection when Stage 2 pruned some alternative for a source the default deployment does not have, with a count per source. Otherwise it returns today's Infeasible.

Correctness:

  • The expansions of the two old retention rules match them exactly:

    • raw data: (query_time ∨ across) ∧ Scan ∧ ¬raw_data_retained;
    • query-time results: query_time ∧ across ∧ ¬query_time_results_retained.

    The Stage 2 tests of these prunes pass with only the reason renamed.

  • The default's only exclusion is the query-time-results one, so planning with the defaults prunes what it pruned before. Stage 3 does not count that exclusion, so the default reports Infeasible as before (only_exclusions_beyond_the_default_deployments_make_the_rejection). an_exclusion_matching_nothing_changes_nothing and the unchanged pass/fail sets of every existing suite (see Verification) check this.

  • A matched candidate never reaches Stage 3, so it is never selected: some_node_matches is false on every selected plan in deployment_exclusions.rs.

  • The Pass 1 skip keeps the selected plans: across 101 workloads × 5 capability sets (see Verification), all 505 plans, costs, MILP objectives, MILP sizes and Stage 2 physical-candidate counts are identical to the previous head d9ecc8bd9, which skipped nothing in Pass 1.

Complexity: O(alternatives × exclusions) matches in Stage 2, each at most O(measures). The supported-summaries expansion has at most SketchAlgorithm::ALL.len() entries plus the readouts of the listed algorithms.

Limits:

  • Family, θ and mergeability match state builds (SummaryAgg, SummaryTumblingWindowChain) only. Merges, estimates and finalizations over an excluded build lose their producer.
  • Pass 1 skips only what an exclusion rules out as a whole family or readout. A deployment that excludes KLL only when merged across windows still has its KLL builds planned through Pass 1 and Pass 2, and pruned in Stage 2.
  • When exclusions matched and no plan is left, the rejection does not say whether the workload would be infeasible without them, because that needs a second solve. Its reason says so.

Decisions and open questions

Decided (by the user, before implementation):

  • The filter runs in Stage 2, and Pass 1 stops filtering supported_summaries. After review, Pass 1 reads the same exclusions() list to skip sketch algorithms excluded outright (one source of truth, no second filter), which restores main's planning time for restricted deployments.
  • Q-P1-1: the exclusions travel in PlanningModels::deployment_capabilities.
  • Q-P1-2: ExcludedByDeployment is not a failed check.
  • Q-P1-3: one cause, whose message says the workload may also be infeasible without the exclusions.
  • The tests of this PR, as written.

Needs reviewer decision:

  1. aggregate_measure is a string (decided in final review, L3: keep it a string on the wire): the AggIntent JSON kind, e.g. "rate", as OperatorCost::measure already is. validate refuses a name that is no measure's kind; AggIntent::is_kind_name asks serde whether the tag is a known variant. A typed enum would duplicate the 40 intent kinds.
  2. Reset handling also covers irate and resets, and extrapolation also covers delta, following PromQL's definitions.
  3. aggregate_measure validation (review L3, not done): is_kind_name still relies on serde's unknown variant error text. A validating newtype AggregateMeasureKind would still need a way to list the measure kinds, which today only that error gives, so it was not small enough for this PR.
  4. Plan for a target's deployment capabilities #1370's names: this PR uses exclusions(), because the items are CandidateExclusions, and the existing NoValidCandidate with RejectionCause::ExcludedByDeployment. Plan for a target's deployment capabilities #1370 proposes restrictions() and NoDeployablePlan.
  5. Defaults in the rejection: the default deployment's own exclusion is left out of the ExcludedByDeployment rejection and its counts, which keeps Q-P1-3's "no exclusion matched → Infeasible" for default planning. The other way is to list it too, but then every infeasible workload under the defaults would be reported as excluded by the deployment.

Rebased onto main b5fcdc0

Previous head 7834fed4d (backup branch backup/test/deployment-exclusions-7834fed4d). Main gained the terse/--verbose devtools text and viewer redesign, the MetricsQL matching modifiers, filtered ingestion-time summary builds, and one more change. Conflicts and resolutions:

  • tools/dag-viewer/stages.js: main replaced deploymentText with settingsRows. Kept settingsRows; this PR's capability lines moved into capabilityLimitsText(capabilities), shown as a "left out" row only when a deployment leaves something out. stages.test.mjs calls capabilityLimitsText, and checks the summary_type wire field through settingsRows.
  • crates/devtools/src/planning_stages_text.rs: kept main's terse/verbose structure, legends and write_physical_by_logical_candidate; this PR's semantics stay: the terse Stage 2 count line counts ExcludedByDeployment(<source>) per source, and verbose rows print the reason through prune_reason_text.
  • tools/dag-viewer/test_viewer.py (new on main): the pruned-reason line now reads "excluded by the deployment: query time results not retained", as in memo.test.mjs.
  • p90-kll.json is unchanged: regenerating it at the new head gives the committed document.

Checked at the new head against main b5fcdc0fe, by test name: types, Pass 1, Stage 2, Stage 3, planner, devtools and integration tests 758 pass, 10 fail, all 10 also failing on main (joint_search_equivalence ×2, materialized_views, planner_fuzz ×3, plan_sharing ×2, promql_to_post_asap, summary_sharing); corpus and sketch plan snapshots pass in check mode; viewer Node 35/35 and Python 81/81; cargo clippy --workspace --all-targets --all-features -- -D warnings clean. asap_planner --run-until stage3 --format text (terse and --verbose) on 10 viewer workloads differs from main only in the Stage 2 reason text (QueryTimeResultsNotRetained → ExcludedByDeployment(query_time_results_not_retained)) and MILP solve times.

Verification

Built with the shared build environment. cargo fmt --all --check and cargo clippy --all-targets on the changed crates are clean. The changed crates' suites ran at this head and were compared by name with main 1760a69f5 (main has not moved). No test fails here that passes on main.

Scope Command Result at this head Newly failing vs main Notes
types, Stage 1 Pass 1, Stage 2, Stage 3, planner, integration, devtools cargo test --no-fail-fast -p asap-types -p asap-stage1-pass1-per-computation-candidates -p asap-stage2-physical-optimization -p asap-stage3-plan-selection -p asap-planner -p asap-integration-tests -p asap-devtools 752 pass, 10 fail 0 the 10 also fail on main: planner summary_sharing::identical_ungrouped_queries_share_their_producers; integration joint_search_equivalence ×2, materialized_views, plan_sharing ×2, promql_to_post_asap; devtools planner_fuzz ×3. 47 tests are new; the only main tests gone are the renamed defaults test and unsupported_summaries_are_not_offered
viewer JS node --test tools/dag-viewer/stages.test.mjs tools/dag-viewer/memo.test.mjs with asap_planner built 35 of 35 0
viewer Python cd tools/dag-viewer && python3 -m unittest -v test_viewer test_server 81 of 81 0

Plans unchanged by the Pass 1 skip, and planning time. Both release binaries (d9ecc8bd9, which plans every summary in Pass 1, and this head) ran asap_planner --run-until stage3 over 101 workloads: 24 showcase (21 single-query and joint workloads at 1 Hz/10 s and 10 Hz/60 s, plus viewer examples 1, 3a and 3b) and the 77 sketch-heavy workloads, each under 5 capability sets: CLI default {}, exact-only {"supported_summaries": []}, HLL-only, KLL-only, and MVP. All 505 plans, costs, MILP objectives, MILP sizes, physical-candidate counts and rejection texts are identical. Times are the median of 3 runs, each pinned to one core, --format text:

Set Capabilities Pass 1 candidates Logical candidates after Pass 2 Planning time, whole set Per workload
Sketch-heavy (77) exact-only 22,630 → 530 26,351 → 683 6.30 s → 2.47 s (×0.39) median ×0.76, best ×0.14
Sketch-heavy HLL-only 22,630 → 632 26,351 → 785 6.30 s → 2.53 s (×0.40) median ×0.77
Sketch-heavy KLL-only 22,630 → 539 26,351 → 711 6.34 s → 2.50 s (×0.39) median ×0.76
Showcase (24) exact-only / HLL-only / KLL-only 1,354 → 238 / 238 / 406 1,590 → 298 / 298 / 498 ×0.88 / ×0.88 / ×0.91
Both CLI default, MVP unchanged unchanged ×1.00–1.01

The restricted counts are back to main's (683 and 711 logical candidates on the sketch-heavy set under exact-only and KLL-only). No planning-time regression test was added: wall-clock tests are not reliable here, and exact_only_capabilities_offer_no_summary pins the candidate count that causes the time instead.

End to end, with the CLI (asap_planner --run-until stage3 --format json, on the rate workload of "Behavior"):

  • On main, both capability files are refused: unknown field `state_not_mergeable_across_windows` and unknown field `counter_semantics` .
  • At this head, {"state_not_mergeable_across_windows": [...]} selects query-time Scan → TimeRange → SummaryAgg → FinalizeExactAccumulator at 0.367671 per second.
  • At this head, {"counter_semantics": {"extrapolation": false}} gives: no valid candidate: [Rejection { id: "workload", cause: ExcludedByDeployment, reason: "query 0 has no candidate left to answer it; excluded by the deployment: counter_not_extrapolated (7 candidates); the workload may be infeasible without these exclusions too" }].

Expected values: every cost and count in the tests commit holds at this head unchanged:

  • costs: 0.060946, 0.061518, 0.062491, 0.072584, 0.060534, 0.113237, 0.279284, 0.367671, 1.490206, 3.953715 and 0.447669 per second;
  • pruned counts: 5, 10, 8, 3, 7, 4 and 2. (Pass 1 skips sketch algorithms only, so the 5 excluded Rate states are still pruned in Stage 2.)

Existing tests whose expected values change, and why:

  • devtools/tests/asap_planner.rs::deployment_capabilities_flag_sets_the_capabilities_and_shows_them: the echoed deployment_capabilities also lists the three new fields with their defaults. "Pass 1 offers no DDSketch candidate" under KLL-only capabilities holds again, as on main.
  • tools/dag-viewer/test-fixtures/p90-kll.json, regenerated with the README command: the memo and stage3_plan_selection are as on main; Stage 2's 36 pruned alternatives carry the new reason encoding, and deployment_capabilities lists the new fields.
  • memo.test.mjs: a Stage 2 line reads "excluded by the deployment: query time results not retained". Everything else is as on main.

Review fixes (independent review of d9ecc8bd9)

  • M1: Pass 1 skips a Summary(algorithm) way when a summary_family-only exclusion from the same exclusions() list matches it (numbers above). Tests written first and seen failing: exact_only_capabilities_offer_no_summary, a_partial_exclusion_keeps_the_summary, an_excluded_exact_family_is_left_to_stage_2, a_family_is_excluded_outright_only_by_a_family_only_exclusion.
  • M2: costing_failures is shared by infeasible and excluded_by_deployment, so the rejection keeps ; executions left out because they could not be costed: … (the_exclusion_rejection_keeps_the_costing_failures). The MVP cause change is listed under "Behavior".
  • L1: validate refuses an exclusion two of whose fields match no operator in common: family or θ (then also merged_across_windows, since removed) with an operator other than a state build; aggregate_measure with one other than Aggregate; readout with one other than SummaryEstimate or with a build-only field; per_entity_reduction with an operator without a reduction (self_contradicting_exclusions_are_rejected, written first).
  • L2: CandidateDescription::of_plan_node moved into the integration test as description_of_plan_node. The C generic stays, because that test still describes plan nodes, whose operators name inputs by NodeId.
  • L3: not done; see "Needs reviewer decision" 3.
  • L4–L7: ASAPOp::produced_state calls Schema::summary_state_type; DeploymentExclusion::candidates is now exclusion; the viewer's deployment line reads summary_type (it showed undefined (Quantile)); the moved OperatorKind comment no longer names a PR.

New tests, by purpose:

  • Stage 1 Pass 1: exact-only capabilities offer no summary; a readout-only or merge-only exclusion keeps the summary; an excluded exact family is left to Stage 2.
  • types:
    • self-contradicting exclusions are refused, and family_excluded_outright holds only for a family-only exclusion;
    • matching on timing + operator, unset fields, lifetime and per-entity reduction;
    • family and θ match builds only;
    • aggregate_measure, the counter-semantics and mergeability expansions, and readout;
    • the default expansion, each capability's expansion and the supported-summaries expansion;
    • invalid exclusions, by index;
    • JSON of the sweep's stored arm and of the new fields;
    • SummaryFamily::of and θ range bounds.
  • Stage 2:
    • a caller exclusion prunes like a capability;
    • a capability is named before a caller exclusion;
    • unsupported summaries and readouts are pruned.
  • Stage 3: only exclusions beyond the default deployment's make the rejection, its reason counts them, and it keeps the costing failures.
  • integration:
    • an exclusion matching nothing changes nothing;
    • the KLL k range moves the state from 547 to 1,404, then 2,863;
    • excluding every KLL size gives the exact quantile;
    • the stored arm;
    • excluding the only feasible candidate gives ExcludedByDeployment;
    • Stage 2 counts per index;
    • an empty exclusion is refused;
    • no mergeable rate or increase state;
    • excluding the rate state alone gives Aggregate[rate], until the measure is excluded too;
    • without extrapolation there is no rate plan and irate is unchanged; without reset handling, neither is planned.
  • planner: exclusions reach Stage 2 through plan_installable and e2e_plan.
  • crate_graph: no planning crate reads environment variables. This guard passes on main too.
  • viewer: the deployment line names each capability left out and each supported summary by summary_type, and the new reason reads as words.

Final review fixes

Commit 7834fed4d on top of ceb78acf4 (backup branch backup/test/deployment-exclusions-ceb78acf4).

Item Status
1. M1: delete CandidateExclusion::counter_semantics, CounterSemantics, needed_by_measure/needed_by_state; exclusions() expands counter_semantics into plain exclusions done. Extrapolation off → measures rate, increase, delta + Exact(Rate), Exact(Increase). Reset handling off → rate, increase, i_rate, resets + `Exact(Rate
2. M2: delete merged_across_windows done; {family, operator: SummaryTumblingWindowChain} + {family, kept_across_evaluations: true} (a_family_not_mergeable_across_windows_expands_into_its_chains_and_kept_builds)
3. Layering: Stage 3 no longer builds DeploymentCapabilities::default() done: ExclusionSource::in_default_deployment and Display for ExclusionSource (asap-types), used by Stage 3; the Stage 2 text count line and full rows print ExcludedByDeployment(<source>)
4. Names done: sketch_parameters → sketch_parameter_range; OperatorKind docs keep "operator without its arguments", per-unit pricing moved to OperatorCost::ns_per_unit
5. Consistent stage inputs done: the facade (and planning_stages) expands the exclusions once; Pass 1 and Stage 2 both take &[DeploymentExclusion]
6. Pass 1 readout-only skip done: readout_excluded_outright; test an_excluded_readout_of_the_measure_skips_the_summary. kll-noreadout Pass 1 candidates drop back (e.g. 222 → 137, 236 → 110) with identical plans
7. aggregate_measure doc done: it matches the Aggregate only; points to {"summary_family": {"exact": "Rate"}}. L3: stays a String
8. Parse aggregate_measure once (optional) declined: replacing is_kind_name's trial deserialization cleanly needs a kind enum mirroring ~40 AggIntent variants; not small enough here
9. Dead code and nits done: stale viewer reason → no_ingestion_pipeline; ExecutionCosts Default is cfg_attr(test); ExclusionSource drops Deserialize; CandidateDescription doc; crate_graph checks env::var only; "an arm with no query-time scan" wording; error is now deployment capabilities: excluded candidate 0: … (no doubled prefix)
10. Docs done: extend guide (new capability = field + expansion + ExclusionSource), library-api link, planner-layering Pass 1/Stage 2 wording, architecture test file name, user guide section with the three fields and CandidateExclusion JSON, glossary SummaryFamily vs StateFamily, title scope

Verification of the fixes (release binaries of main, ceb78acf4 and 7834fed4d):

  • Tests of the changed crates (asap-types, asap-cost, Pass 1, Stage 2, Stage 3, asap-planner, asap-integration-tests, asap-devtools): all pass except the 10 that fail on main too (joint_search_equivalence ×2, materialized_views, planner_fuzz ×3, plan_sharing ×2, promql_to_post_asap, summary_sharing). Viewer JS: 29 pass, 1 skipped (as before). cargo fmt --check and cargo clippy --tests -D warnings on the changed crates are clean.
  • Default deployment, 47 viewer workloads, --format text: identical to main except the Stage 2 count line (QueryTimeResultsNotRetained N → ExcludedByDeployment(query_time_results_not_retained) N) and MILP solve times.
  • Restricted matrix (18 capability files × 14 workloads, including no-extrap, no-resets, not-mergeable, sum-notmerge, no-qt-rate, param-range, kll-noreadout and the invalid ones): selected plans, costs and errors are identical to ceb78acf4 in all 252 runs; Stage 2 pruned counts per reason are identical except kll-noreadout, where Pass 1 now skips the KLL builds.
  • Plan for a target's deployment capabilities #1370 acceptance reproduction: column store 211 of 211 planned, 132 at the unrestricted cost; stream aggregation 126 planned, 115 at the unrestricted cost (unchanged).

Wire changes in the fixes: excluded_candidates entries no longer accept counter_semantics or merged_across_windows (use the capability fields, or operator/kept_across_evaluations), and sketch_parameters is now sketch_parameter_range.

Merge order: docs/develop_docs/library-api.md conflicts with #1372; whichever merges second rebases and keeps both edits.

Follow-ups

  • Not covered (Plan for a target's deployment capabilities #1370): per-family guarantee kind; window forms; and capability-level allow-lists of operators, measures and θ ranges. Today these can be expressed only as excluded_candidates.
  • CLI: asap_planner --deployment-capabilities reads the new fields, but the stage text does not list the exclusions yet.

@zzylol zzylol added optimizer Workload optimization and plan selection testing Corpus, regression, differential, or benchmark tests labels Nov 16, 2026
@zzylol
zzylol force-pushed the test/deployment-exclusions branch from 94e966e to aa17a02 Compare November 16, 2026 23:49
@zzylol zzylol changed the title test(types, stage2, planner): deployment exclusions: one filter for a target's capabilities and the caller's exclusions (tests only) feat(types, stage2, stage3): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions Nov 16, 2026
@zzylol
zzylol marked this pull request as ready for review November 16, 2026 23:56
@zzylol zzylol added dag-viewer DAG export and visualization tooling enhancement New feature or request labels Nov 16, 2026
@zzylol zzylol self-assigned this Nov 17, 2026
@zzylol
zzylol requested a review from GordonYuanyc November 17, 2026 05:28
@zzylol zzylol changed the title feat(types, stage2, stage3): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions feat(types, pass1, stage2, stage3, planner, viewer): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions Nov 17, 2026
…clusion with the capability table (tests only)

Tests for harness PR P1, reworked so that a target's capabilities and the
caller's own exclusions expand into one list of CandidateExclusions that
Stage 2 applies as one filter. Adds the dimensions an external target
needs: a query-time aggregate's measure, state merged across windows
versus built within one evaluation, and counter reset handling and
extrapolation.

Stubs only, so the tests compile: every new function body is todo!(),
validate does not check excluded_candidates, Stage 2 and Stage 3 do not
read the new fields. OperatorKind moves unchanged from asap-cost to
asap-types (re-exported by asap-cost) so exclusions can name operators.
…clusions apply as one Stage 2 filter

DeploymentCapabilities::exclusions expands every capability a deployment
lacks, and the caller's excluded_candidates, into CandidateExclusions with
their source. Stage 2 prunes each matched alternative as
ExcludedByDeployment(source); Stage 3 reports no plan left as
RejectionCause::ExcludedByDeployment. Deletes PruneReason::RawDataNotRetained,
QueryTimeResultsNotRetained, the Pass 1 supported-summaries filter,
DeploymentCapabilities::supports and summary_supported.
…te the p90 KLL fixture

Pass 1 now offers every summary the planner builds, so the KLL-only
fixture's memo also holds the DDSketch readout and states that Pass 2
prunes; Stage 2's reasons for capabilities read as
{"excluded_by_deployment": source}. The viewer renders that reason, and
the capabilities echo lists the new defaulted fields.
…ble workload reported as Infeasible

Only exclusion sources the default deployment does not have make the
rejection ExcludedByDeployment, so planning with the defaults reports what
it reported before; a source that pruned one candidate reads "(1 candidate)".
…sions

- Pass 1 skips a summary whose sketch algorithm a summary_family-only
  exclusion from DeploymentCapabilities::exclusions() rules out outright
  (CandidateExclusion::family_excluded_outright), so restricted
  deployments no longer plan every summary; plans are unchanged.
- The ExcludedByDeployment rejection keeps the costing-failure suffix,
  through a helper shared with infeasible.
- validate refuses exclusions whose fields match no operator in common.
- CandidateDescription::of_plan_node moves to the integration test.
- Schema::summary_state_type replaces a duplicate lookup;
  DeploymentExclusion::candidates is renamed exclusion; the viewer reads
  summary_type; a PR number is dropped from a comment.
… fixes for deployment exclusions

- Counter semantics and state mergeability expand into plain exclusions:
  CandidateExclusion loses counter_semantics and merged_across_windows
  (and the CounterSemantics enum); exclusions() emits aggregate_measure
  and summary_family exclusions for the counter functions and states, and
  {family, SummaryTumblingWindowChain} plus {family,
  kept_across_evaluations} per family not mergeable across windows.
- sketch_parameters is renamed sketch_parameter_range.
- ExclusionSource gets Display and in_default_deployment; Stage 3 no
  longer builds DeploymentCapabilities::default(); the Stage 2 count line
  prints ExcludedByDeployment(<source>). ExclusionSource drops Deserialize.
- The facade expands the exclusions once; Pass 1 and Stage 2 both take the
  list.
- Pass 1 also skips a summary whose readout of the measure's statistic is
  excluded outright, as before the exclusions.
- aggregate_measure doc says it matches the Aggregate only; per-unit
  pricing docs move to OperatorCost::ns_per_unit; nits and docs.
@zzylol
zzylol force-pushed the test/deployment-exclusions branch from 7834fed to 41c3d2c Compare November 17, 2026 16:35
@zzylol
zzylol merged commit bc725bd into main Nov 17, 2026
3 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dag-viewer DAG export and visualization tooling enhancement New feature or request optimizer Workload optimization and plan selection testing Corpus, regression, differential, or benchmark tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant